• Have you followed the guidelines in our Contributing document?
• Have you checked to ensure there aren't other open Pull Requests for the same change?
• Have you added an explanation of what your changes do and why you'd like us to include them?
• Have you written new tests for your changes? Here's an example.
• Have you successfully run brew style with your changes locally?
• Have you successfully run brew typecheck with your changes locally?
• Have you successfully run brew tests with your changes locally?

Addresses #18294.

A replacement may be specified like so:

deprecate! date: "2024-01-10", because: :repo_removed, replacement: "ffmpeg"

which yields something like

$ HOMEBREW_NO_INSTALL_FROM_API=1 brew info alac
==> alac: stable 0.2.0 (bottled)
Basic decoder for Apple Lossless Audio Codec files (ALAC)
https://web.archive.org/web/20150319040222/craz.net/programs/itunes/alac.html
Deprecated because it has a removed upstream repository! It will be disabled on 2025-01-10.
Consider replacing it with:
    brew install ffmpeg
Not installed
From: https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/a/alac.rb
License: MIT
==> Analytics
install: 8 (30 days), 34 (90 days), 110 (365 days)
install-on-request: 8 (30 days), 34 (90 days), 110 (365 days)
build-error: 0 (30 days)

and, for disabled:

disable! date: "2024-08-03", because: :unmaintained, replacement: "gcalcli"

which yields something like

$ HOMEBREW_NO_INSTALL_FROM_API=1 brew info gcal
==> gcal: stable 4.1 (bottled)
Program for calculating and printing calendars
https://www.gnu.org/software/gcal/
Disabled because it is not maintained upstream! It was disabled on 2024-08-03.
Consider replacing it with:
    brew install gcalcli
Not installed
From: https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/g/gcal.rb
License: GPL-3.0-or-later
==> Dependencies
Build: texinfo ✔
==> Analytics
install: 0 (30 days), 2 (90 days), 179 (365 days)
install-on-request: 0 (30 days), 2 (90 days), 179 (365 days)
build-error: 0 (30 days)

• Replacements are added as an optional keyword argument. The message and behavior when no replacement is provided should remain the same.
• I made an effort to include the replacement in the API JSON as well, but I'm not too familiar. Would appreciate if someone can confirm that the changes made there are sufficient.
• The replacement is just a string for now, which is shown as an argument to the brew install help text. Note that there is no distinction between the string argument as a formula or cask; there is no validation on the value of the string.
• I am aware that formula: allow excluding deprecate! reason when disable! exists #18661 is open and this may need to be refactored after that is merged (or vice versa).